## Overview

This PR introduces the `.map()` method to the Flow DSL, enabling users to define map-type steps that process arrays element-by-element. This completes the DSL support for the map step infrastructure that was previously added to the SQL Core layer.

## Problem

Previously, while the SQL Core supported map steps (with `step_type => 'map'`), there was no way to define them via the TypeScript DSL. Users had to manually write SQL or work around this limitation.

## Solution

The new `.map()` method provides a type-safe, intuitive way to define map steps with these key characteristics:

### API Design

```
// Root map - processes flow input array
new Flow<string[]>({ slug: 'text_processing' })
  .map({ slug: 'normalize' }, (text) => text.trim().toLowerCase())

// Dependent map - processes another step's array output
new Flow<{}>({ slug: 'workflow' })
  .array({ slug: 'fetch_items' }, () => fetchData())
  .map({ slug: 'enrich', array: 'fetch_items' }, (item) => ({
    ...item,
    enriched: true
  }))
```

### Key Features

1. **Intuitive dependency syntax**
    - Omit `array` property for root maps (processes flow input)
    - Use `array: 'stepSlug'` for dependent maps (single dependency only)
2. **Different handler signature**
    - Map handler: `(item, context) => Json`
    - Regular step handler: `(input, context) => Json`
    - Map handlers receive individual array elements, not the full input object
3. **Type safety**
    - Enforces Json-compatible types for inputs and outputs
    - Full TypeScript inference for item types based on dependencies
    - Compile-time validation that dependencies return arrays
4. **SQL generation**
    - Correctly adds `step_type => 'map'` parameter to `pgflow.add_step()`
    - Maintains proper parameter ordering: dependencies, options, then step_type

## Implementation Details

### Changes Made

1. **Extended StepDefinition interface** (`dsl.ts`)
    - Added optional `stepType?: 'single' | 'map'` property
    - Defaults to 'single' for backward compatibility
2. **Implemented** **`.map()`** **method** (`dsl.ts`)
    - Complex type signatures for proper inference
    - Runtime validation for dependencies
    - Stores `stepType: 'map'` in step definition
3. **Updated compile function** (`compile-flow.ts`)
    - Checks for `stepType` property
    - Adds `step_type => 'map'` parameter when needed
4. **Comprehensive test coverage**
    - Type tests: 20 tests covering constraints and inference
    - Runtime tests: 12 tests for SQL generation
    - Integration tests: 12 tests for complete workflows
    - Example flows demonstrating various use cases

### Technical Decisions

- **Optional** **`array`** **key**: Mirrors the `dependsOn` pattern (no key = root step)
- **Single dependency constraint**: Enforced at both type and runtime levels
- **Handler signature difference**: Clear distinction between map and regular steps
- **Type parameter ordering**: Worked around TypeScript constraints for optional parameters

## Testing

The implementation follows TDD principles with:

- ✅ Type safety tests (inference, constraints, edge cases)
- ✅ SQL generation tests (parameter ordering, step_type inclusion)
- ✅ Integration tests (complete workflows, validation)
- ✅ Example flows (data processing, ETL, parallel maps)

## Migration Guide

No breaking changes. Existing flows continue to work unchanged. To use map steps:

1. For root maps (array input):
2. For dependent maps:

## Future Considerations

- The `input.run` convention will be removed in future versions
- Map steps are ready for this transition (handlers don't use `input.run`)
- Type system properly handles both root and dependent map cases

## Checklist

- [x] Implementation complete with type safety
- [x] SQL generation working correctly
- [x] Comprehensive test coverage
- [x] Example flows created
- [x] No breaking changes
- [x] Documentation in changeset

## Related Issues

Part of the map infrastructure implementation series (see [PLAN.md](http://PLAN.md))